home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / LANG / BASIC / LIB / EVENTSHELL / DOCS / Events < prev    next >
Text File  |  1996-04-11  |  20KB  |  730 lines
  1. PROCshell_AttachPaletteChangeHandler()
  2. =>    str    function name
  3.  
  4. Registers a function name to be called when a PaletteChange
  5. message is received. This occurs when the user has finished
  6. dragging the sliders on the Palette application, or when a
  7. new palette is loaded. It is also called when the handler is
  8. set up so that the user application can note the current
  9. parameters.
  10.  
  11. Note that this message is not issued when the screen mode
  12. changes, so tasks interested in colour mapping changes should
  13. call PROCshell_AttachModeChangeHandler as well.
  14.  
  15. User FN (PROCshell_AttachPaletteChangeHandler)
  16. =>    None
  17.  
  18. This function is called when a PaletteChange message is
  19. received and also when PROCshell_AttachPaletteChangeHandler
  20. is called.
  21.  
  22. --------------------------------------------------------
  23.  
  24. PROCshell_AttachModeChangeHandler()
  25. =>    str    function name
  26.  
  27. Registers a function name to be called when a ModeChange
  28. message is received. This allows the application to check
  29. any mode-specific parameters such as screen width etc. It
  30. is also called when the handler is set up so that the user
  31. application can note the current parameters.
  32.  
  33. User FN (PROCshell_AttachModeChangeHandler) 
  34. =>    None
  35.  
  36. This function is called when a ModeChange message is
  37. received and also when PROCshell_AttachModeChangeHandler
  38. is called
  39.  
  40. --------------------------------------------------------
  41.  
  42. PROCshell_AttachTaskInitialiseHandler()
  43. =>    str    function name
  44.  
  45. Registers a function name to be called when a TaskInitialise
  46. message is received. This allows the application to keep
  47. track of any new tasks started after it.
  48.  
  49. User FN (PROCshell_AttachTaskInitialiseHandler)
  50. =>    int    task handle
  51.     str    task name  
  52.  
  53. <=    int    ignored
  54.  
  55. This function is called when a TaskInitialise  message is
  56. received.
  57.  
  58. --------------------------------------------------------
  59.  
  60. PROCshell_AttachTaskCloseDownHandler()
  61. =>    str    function name
  62.  
  63. Registers a function name to be called when a TaskCloseDown
  64. message is received.This message is sent when a task (other
  65. than the current one) is killed.
  66.  
  67. User FN (PROCshell_AttachTaskCloseDownHandler)
  68. =>    None
  69.  
  70. This function is called when a TaskCloseDown message is
  71. received.
  72.  
  73. --------------------------------------------------------
  74.  
  75. PROCshell_AttachPane()
  76. =>    int    window handle
  77.     int    pane handle
  78.     int    pane flags
  79.     int    x offset of pane relative to parent window
  80.     int    y offset of pane relative to parent window
  81.  
  82. Pane Flags (PROCshell_AttachPane)
  83. 0    =    attached to parent window work area
  84. 1    =    not used
  85. 2    =    attached to left edge
  86. 3    =    attached to bottom edge
  87. 4    =    attached to right edge
  88. 5    =    attached to top edge
  89.  
  90. If necessary the window flags of the pane window are
  91. changed so that the 'pane' bit is on and the 'moveable'
  92. bit is off, so that editing the template file is not
  93. required.
  94.  
  95. --------------------------------------------------------
  96.  
  97. PROCshell_HidePane
  98. =>    int    parent window handle
  99.     int    pane window handle
  100.  
  101. Detaches a pane from a parent window and closes it.
  102. The pane can be reopened with PROCshell_ShowPane
  103.  
  104. --------------------------------------------------------
  105.  
  106. PROCshell_ShowPane
  107. =>    int    parent window handle
  108.     int    pane window handle
  109.  
  110. Reopens a pane that has been hidden with
  111. PROCshell_ShowPane
  112.  
  113. --------------------------------------------------------
  114.  
  115. PROCshell_AttachDataLoad()
  116. =>    int    window handle
  117.     int    icon handle
  118.     int    filetype to recognise and optionally
  119.            load (see no load flag)
  120.     str    function name
  121.     bool    no load flag
  122.  
  123. Note that it is possible to call this function for
  124. the same window/icon pair more than once giving
  125. different filetypes (and function names if required)
  126. to allow the handling of multiple filetypes.
  127.  
  128. User FN (PROCshell_AttachDataLoad)
  129. =>    int    address file has been loaded at
  130.     int    filetype of file
  131.     str    full pathname of file
  132.     int    file size (from dataload message)
  133.  
  134. Note that if the event was attached with the
  135. no load flag set to TRUE the address will
  136. be -1 and the user application is expected to
  137. actually load the file.
  138.  
  139. DataLoad 'No Load' flag
  140. FALSE = data file is loaded in a heap block and
  141.         the name and address is returned to the
  142.         user application.
  143.  
  144. TRUE  = only the data file name and type is
  145.         returned to the user application.
  146.  
  147. This flag is provided for maximum flexibility
  148. when dealing with drag loads. When you are
  149. converting an existing program to run under the
  150. EvntShell system you may already have a working
  151. load routine. In this case set the flag to TRUE
  152. and when a drag load occurs your application will
  153. be told the filename, which may then be loaded
  154. and processed as required.
  155.  
  156. When this flag is FALSE the library routines will
  157. reserve a memory block for the file and load it
  158. automatically.
  159.  
  160. For the technical of you out there the library
  161. stores the status of the no load flag in the top
  162. bit of the filetype number. This will end in tears
  163. when RISC-OS 4 comes out...
  164.  
  165. --------------------------------------------------------
  166.  
  167. PROCshell_AttachDataSave()
  168. =>    int    window handle
  169.     int    icon handle
  170.     int    address of heapblock holding data or
  171.            the estimated file size
  172.     int    file type for saved file
  173.     int    icon nr of filename icon
  174.     str    function name (optional if data
  175.            is held in a heapblock)
  176.  
  177. Attaches a datasave handler to a window/icon pair. A
  178. typical use would be in a 'Save As' dialog box, the
  179. icon handle being that of the 'File Type' icon.
  180.  
  181. If icon 0 in the window is clicked on then a check
  182. is made that the filename icon contains a valid
  183. path name, generating an error if it does not.
  184.  
  185. An error may also be generated when the drag starts
  186. if the filename icon is blank. You must specify an
  187. icon handle to contain the file name - if you don't
  188. want the name to be displayed for editable then put
  189. it in a hidden icon (i.e. outside the window visible
  190. area).
  191.  
  192. Note that the third parameter can point to a heap
  193. block containing the data to save which means that
  194. the data must exist in the block (or at least the
  195. block must exist and be the correct size) before
  196. this routine is called. If this parameter is >&8000
  197. it is taken to be a pointer to the heap block , and
  198. the name of the function to perform the save is 
  199. optional. The specified function will be called in
  200. this case.
  201.  
  202. Alternatively this parameter can be an estimated
  203. file size (i.e. <&8000) in which case the user
  204. function may write directly into the file whose
  205. name is given as a parameter to the function. RAM
  206. transfer is not possible if this is the case.
  207.  
  208. The button type of the filetype icon is automatically
  209. changed to click/drag.
  210.  
  211. User FN (PROCshell_AttachDataSave)
  212. =>    str    full filename of file
  213.  
  214. This function is not called if the file is stored
  215. in a heap block. In this case the whole contents of
  216. the heap block are transferred.
  217.  
  218. Estimated File Sizes
  219. It should (if other applications are written to
  220. the Acorn guidelines!) not matter if this estimate
  221. is inaccurate. However, file transfer will be a
  222. little faster if it is accurate and problems may
  223. occur with badly written applications if it is not.
  224.  
  225. --------------------------------------------------------
  226.  
  227. PROCshell_AttachClickSelect()
  228. =>    int    window handle
  229.     int    icon handle 
  230.     str    function name
  231.  
  232. The button type of the icon will be changed
  233. to 'Click' (type 3) if the icon originally
  234. had a type of 'Never' (type 0).
  235.  
  236. User FN (PROCshell_AttachClickSelect)
  237. =>    int    window handle
  238.     int    icon handle
  239.  
  240. --------------------------------------------------------
  241.  
  242. PROCshell_AttachClickAdjust()
  243. =>    int    window handle
  244.     int    icon handle  
  245.     str    function name
  246.  
  247. The button type of the icon will be changed
  248. to 'Click' (type 3) if the icon originally
  249. had a type of 'Never' (type 0).
  250.  
  251. User FN (PROCshell_AttachClickAdjust)
  252. =>    int    window handle
  253.     int    icon handle
  254.  
  255. --------------------------------------------------------
  256.  
  257. PROCshell_AttachUserRedraw()
  258. =>    int    window handle
  259.     str    function name
  260.  
  261. A check is made to ensure that the 'Auto redraw' flag of
  262. the window is off, and the flag is cleared automatically
  263. if necessary (i.e. you don't have to use !FormEd or
  264. similar to set the flag correctly)
  265.  
  266. User FN (PROCshell_AttachUserRedraw)
  267. =>    int    address of block returned by redraw
  268.          request
  269.     int    x origin of window (screen coords)
  270.     int    y origin of window (screen coords)
  271.  
  272. The function to call when a redraw request
  273. is made.
  274.  
  275. --------------------------------------------------------
  276.  
  277. PROCshell_AttachDrag()
  278. =>    int    window handle
  279.     int    icon handle     
  280.     str    function name
  281.  
  282.  
  283. User FN (FNshell_AttachDrag)
  284. =>    int    window handle over which drag
  285.          started
  286.     int    icon handle over which drag was
  287.          started (-1 for no icon)
  288.  
  289. --------------------------------------------------------
  290.  
  291. PROCshell_AttachHelpTag()
  292. =>    int    window handle         
  293.     int    icon handle      
  294.     str    <message tag=>MessageTag>
  295.  
  296. Note that any message tags found in icon
  297. validation strings override tags set up by
  298. this routine.
  299.  
  300. --------------------------------------------------------
  301.  
  302. PROCWimpCloseDown
  303. =>    None
  304.  
  305. Not used in EvntShell library - use <PROCshell_WimpCloseDown_I> instead.
  306.  
  307. --------------------------------------------------------
  308.  
  309. PROCshell_WimpCloseDown_I
  310. =>    None
  311.  
  312. Called when the application shuts down (the library calls
  313. this automatically)
  314.  
  315. --------------------------------------------------------
  316.  
  317. PROCshell_AttachBumpHandler()
  318. =>    int    window handle
  319.     int    icon handle (display value)
  320.     int    icon handle (increment value)
  321.     int    icon handle (decrement value)
  322.     int    lower limit
  323.     int    upper limit
  324.     int    step
  325.     bool    wrap flag
  326.     str    function name 1 (can be "")
  327.     str    function name 2 (can be "")
  328.  
  329. Bump icons are the arrows that allow you to alter the
  330. value displayed in an icon (usually but not necessarily
  331. a writable one). Note that a click on a bump icon with
  332. ADJUST has the opposite effect to a click with SELECT.
  333.  
  334. Pressing SHIFT while clicking on a bump icon will double 
  335. the step value, CTRL will make the step 4 times larger,
  336. SHIFT and CTRL makes the step 8 times larger.
  337.  
  338. User FN1 (PROCshell_AttachBumpHandler)
  339. =>    int    value
  340.     int    mouse button pressed (SELECT = 4,
  341.          ADJUST = 1
  342.  
  343. <=    str converted value
  344.  
  345. This function is called before the new value
  346. is placed in the display icon. 
  347.  
  348. An example would be converting an integer
  349. value to the format 0h00 (i.e hours and mins).
  350.  
  351. DEF FN_dis_fn(val%)
  352. =STR$(val%DIV60)+"h"+RIGHT$("00"+STR$(val%MOD60),2)
  353.  
  354. See the !VBase2 demo app.
  355.  
  356. User FN2 (PROCshell_AttachBumpHandler)
  357. =>    str    value to decode
  358.  
  359. <=    int    converted value
  360.  
  361. This function is called before the new value
  362. is placed in the display icon.
  363.  
  364. An example would be converting a string "0h00"
  365. back to an integer value.
  366.  
  367. DEF FN_decode_dis(val$)
  368. =VAL(val$)*60+VAL(RIGHT$(val$,2))
  369.  
  370. See the !VBase2 demo app.
  371.  
  372. --------------------------------------------------------
  373.  
  374. PROCshell_AttachHotKey()
  375. =>    str    key
  376.     bool    shift flag
  377.     bool    ctrl  flag
  378.     bool    alt   flag
  379.     str    window identifier
  380.     int    window handle
  381.     str    function name
  382.     str    function name
  383.  
  384. Sets up a 'hotkey' event. Function keys F0-F11
  385. (note NOT F12 as the task manager uses it under
  386. RISC-OS 3) are supported.
  387.  
  388. User FN (PROCshell_AttachHotKey)
  389. =>    int    window handle
  390.  
  391. The function to call before opening the window.
  392. A function name of "" may be used if you don't
  393. need to call a function. This would normally be
  394. used to fill in icon fields and set the state
  395. of radio buttons
  396.  
  397. User FN (PROCshell_AttachHotKey)
  398. =>    int    window handle
  399.  
  400. The function to call after opening the window.
  401. A function name of "" may be used if you don't
  402. need to call a function.
  403.  
  404. Key (PROCshell_AttachHotKey)
  405. The key string normally consists of one ASCII
  406. character i.e. "R". When the ctrl flag is set
  407. this would cause the actions to be carried out
  408. when CTRL-R is pressed.
  409.  
  410. The string may also contain "F1" to "F11" to
  411. allow function keys to be used. No checking is
  412. performed on the string.
  413.  
  414. Window (PROCshell_AttachHotKey)
  415. The window identifier specifies the name
  416. of the window you want to appear when the
  417. keypress is received. This parameter is
  418. optional as you might not always want to
  419. open a window.
  420.  
  421. The window is a 'dynamic' dialog box which
  422. will disappear when <ESC> is pressed and
  423. is opened in such a position that the mouse
  424. pointer is in the middle of the window
  425. (where possible).
  426.  
  427. Window Handle (shell_AttachHotKey)
  428. When this is >0 then the window
  429. created will be static i.e. it will not
  430. be removed when the mouse is clicked
  431. outside it, or when <ESC> is pressed.
  432.  
  433. --------------------------------------------------------
  434.  
  435. PROCshell_DoBackgroundTask
  436. =>    None
  437.  
  438. Called everytime a null reason code is received
  439.  
  440. --------------------------------------------------------
  441.  
  442. PROCshell_HandleUnknownMessage()
  443. =>    int    address of message block
  444.  
  445. Called every time an unknown message is received.
  446.  
  447. --------------------------------------------------------
  448.  
  449. PROCshell_AttachCloseWindowHandler()
  450. =>    int    window handle
  451.     str    function name
  452.  
  453. Registers a function name to be called when an 
  454. CloseWindow message is received. This is useful
  455. to prevent the window closing if so doing
  456. would involve loss of data.
  457.  
  458. This message is issued when the window close
  459. icon is clicked on.
  460.  
  461. User FN (PROCshell_AttachCloseWindowHandler)
  462. =>    int    window handle
  463.  
  464. <=    bool    0 to disallow close, non 0 to
  465.          close
  466.  
  467. --------------------------------------------------------
  468.  
  469. PROCshell_AttachOpenWindowHandler()
  470. =>    int    window handle
  471.     str    function name
  472.  
  473. Registers a function name to be called when an 
  474. OpenWindow message is received. This is useful
  475. so that the application can set a flag to
  476. avoid doing window redraws while the window is
  477. closed for example.
  478.  
  479. This message is issued when the window is
  480. dragged around the screen as well as when
  481. the program opens the window. You should avoid
  482. doing time consuming stuff in the function that
  483. is called therefore.
  484.  
  485. User FN (PROCshell_AttachOpenWindowHandler)
  486. =>    None
  487.  
  488. <=    bool    0 to disallow open, non 0 to
  489.          open
  490.               
  491. --------------------------------------------------------
  492.  
  493. PROCshell_AttachPreQuitHandler()
  494. =>    str    function name
  495.  
  496. Registers a function name to be called when a 
  497. PreQuit message is received. This gives the
  498. application a chance to save data or abort
  499. the shutdown.
  500.  
  501. This message is issued when the task is quit
  502. from the Task Manager, or when CTRL-SHIFT-F12
  503. is pressed (under RISC OS 3).
  504.  
  505. User FN (PROCshell_AttachPreQuitHandler)
  506. =>    None
  507.  
  508. <=    bool    non 0 to allow quit, 0 to
  509.          cancel quit
  510.  
  511. This function is called when a PreQuit
  512. message is received.
  513.  
  514. --------------------------------------------------------
  515.  
  516. PROCshell_AttachColourPopupMenu()
  517. =>    int    window handle
  518.     int    menu    icon handle
  519.     int    display icon handle
  520.     int    menu handle
  521.     str    user function (optional)
  522.  
  523. Provides for automatic updating of a display
  524. icon when a selection is made from the
  525. attached colour menu. If a user function name
  526. is not supplied then the display icon shows
  527. the selected menu item background colour.
  528.  
  529. The button type of the menu icon is changed
  530. to 3 to ensure the menu opens when <SELECT>
  531. is used.
  532.  
  533. --------------------------------------------------------
  534.  
  535. PROCshell_AttachPopupMenu()
  536. =>    int    window handle
  537.     int    menu icon handle
  538.     int    display icon handle
  539.     int    menu handle
  540.     str    notify  function (optional)
  541.     str    preopen function (optional)
  542.  
  543. Provides for automatic updating of a display
  544. icon when a selection is made from the
  545. attached menu. If a user function name is
  546. not supplied then the display icon shows
  547. the selected menu item text.
  548.  
  549. The button type of the menu icon is changed
  550. to 3 to ensure the menu opens when <SELECT>
  551. is used.
  552.  
  553. Notify FN (AttachPopupMenu)
  554. =>    int    window handle
  555.     int    display icon handle
  556.     str    menu text of selected item
  557.  
  558. <=    bool    TRUE if text should be inserted
  559.          in the display icon, FALSE
  560.          otherwise
  561.  
  562. PreOpen FN (PROCshell_AttachPopupMenu)
  563. =>    int    handle of menu
  564.  
  565. <=    int    no meaning
  566.  
  567. It is possible that the menu handle could be 0,
  568. denoting that no menu has been created. In this
  569. case the handle can be ignored and a new menu
  570. created.
  571.  
  572. --------------------------------------------------------
  573.  
  574. PROCshell_AttachPopupDatePicker()
  575. =>    int    window handle
  576.     int    menu icon handle
  577.     int    display icon handle (may be -1)
  578.     str    notify FN (may be "")
  579.     str    preopen FN (may be "")
  580.  
  581. This popup displays a Calendar for the current
  582. month (although the month may be incremented
  583. and decremented) enabling the selection of a
  584. date.
  585.  
  586. To use this popup two extension libraries must
  587. be loaded, CalLib and DatePick. This can be done
  588. as follows:
  589.  
  590. void% = FNshell_InstallLib( "<EvntShell$Path>
  591.         Extensions.CalLib" )
  592. void% = FNshell_InstallLib( "<EvntShell$Path>
  593.         Extensions.DatePick" )
  594.  
  595. In addition a template called 'datepicker' must
  596. exist in the loaded template file. This can be
  597. found in the !EvntShell application in the
  598. directory Resources.UK.Templates.2D and 3D. The
  599. appearance may be edited but the icons may not
  600. be renumbered.
  601.  
  602. The message file must also include the following
  603. tokens:
  604.  
  605. #message strings for CalLib
  606. monthstr:JanFebMarAprMayJunJulAugSepOctNovDec
  607. daystr:SunMonTueWedThuFriSat
  608. today:Today
  609.  
  610. Notify FN (PROCshell_AttachPopupDatePicker)
  611. =>    str    date in dd.mm.yy format
  612.  
  613. This function is called when a valid
  614. selection has been made in the DatePicker
  615. popup. If this function is supplied then
  616. it is up to your application to act on
  617. the returned date. Otherwise the specified
  618. display icon is updated with the string.
  619.  
  620. PreOpen FN (PROCshell_AttachPopupDatePicker)
  621. =>    int window handle of dbox
  622.  
  623. <=    int    no meaning
  624.  
  625. --------------------------------------------------------
  626.  
  627. FNEvnts_GetLastMouseButtonClicked()
  628. =>    None
  629.  
  630. Returns the value of the last mouse button
  631. pressed. 4 = SELECT, 2 = MENU, 1 = ADJUST
  632.  
  633. --------------------------------------------------------
  634.  
  635. PROCshell_AttachIconWatch()
  636. =>    int    window handle
  637.     int    icon handle
  638.     str    function to call when value
  639.          changes
  640.  
  641. User FN (PROCshell_AttachIconWatch)
  642. =>    str    new icon contents
  643.  
  644. <=    int    no meaning
  645.  
  646. --------------------------------------------------------
  647.  
  648. PROCshell_AttachMenuHelpTag()
  649. =>    str    menu name
  650.     int    item handle
  651.     str    message tag
  652.  
  653. This facility is only available under Risc OS 3 or
  654. later.
  655.  
  656. --------------------------------------------------------
  657.  
  658. FNshell_Evnts_DragIconStartIcon
  659. =>    None
  660.  
  661. <=    int    icon handle the drag started on
  662.  
  663. --------------------------------------------------------
  664.  
  665. FNshell_Evnts_DragIconStartWindow
  666. =>    None
  667.  
  668. <=    int    window handle the drag started in
  669.  
  670. --------------------------------------------------------
  671.  
  672. FNshell_Evnts_WritableDragInProgress
  673. =>    None
  674.  
  675. <=    bool    TRUE if a drag is in progress, FALSE
  676.          otherwise
  677.  
  678. --------------------------------------------------------
  679.  
  680. PROCshell_AttachSaveDesktopHandler()
  681. =>    str    function name
  682.  
  683. Registers a function name to be called when a save desktop
  684. message is received. This occurs when the user has selected
  685. 'Desktop boot -> Save' from the iconbar menu of the Task
  686. Manager. 
  687.  
  688. If this routine is not called then the line added to the desktop
  689. boot file is a command to run the application when the file
  690. is executed. However, it is possible to specify the line added
  691. to the file using this routine which enables the command line
  692. to contain the name of the currently loaded file for example.
  693.  
  694. User FN (PROCshell_AttachSaveDesktopHandler)
  695. =>    None
  696.  
  697. <=    str    command line to add to the desktop boot file
  698.          currently being written.
  699.  
  700. --------------------------------------------------------
  701.  
  702. PROCshell_AttachDeskFontChangeHandler()
  703. =>    str    function name
  704.  
  705. Registers a function name to be called when a desktop
  706. font change message is received.
  707.  
  708. User FN (PROCshell_AttachDeskFontChangeHandler)
  709. =>    int    handle of new font
  710.  
  711. <=    int    (no meaning)
  712.  
  713. --------------------------------------------------------
  714.  
  715. PROCshell_AttachPointerEnteringWindowHandler
  716. =>    str    user FN to call when event occurs
  717.  
  718. User FN (PROCshell_AttachPointerEnteringWindowHandler)
  719. =>    int    window handle
  720.          
  721. --------------------------------------------------------
  722.  
  723. PROCshell_AttachPointerLeavingWindowHandler
  724. =>    str    user FN to call when event occurs
  725.  
  726. User FN (PROCshell_AttachPointerLeavingWindowHandler)
  727. =>    int    window handle
  728.          
  729. --------------------------------------------------------
  730.